home *** CD-ROM | disk | FTP | other *** search
/ Openstep 4.2 (Developer) / Openstep Developer 4.2.iso / NextDeveloper / Headers / streams / streams.h next >
Encoding:
C/C++ Source or Header  |  1996-08-30  |  10.1 KB  |  321 lines
  1. /*
  2.  *    File:    streams.h
  3.  *    Author:    Avadis Tevanian, Jr.
  4.  *
  5.  *    Header file definitions.
  6.  */
  7.  
  8. #ifndef STREAMS_H
  9. #define STREAMS_H
  10.  
  11. #ifdef NeXT_PDO
  12. #include <stdarg.h>        // va_start
  13. #include <mach/mach.h>
  14. #else    NeXT_PDO
  15. #import <stdarg.h>
  16. #import <mach/port.h>
  17. #endif NeXT_PDO
  18. #if defined(WIN32)
  19. #import <objc/objc-api.h>
  20. #endif
  21. #import <objc/error.h>
  22. #if !defined(NEXTPDO)
  23. #define NEXTPDO extern
  24. #endif
  25.  
  26. /* This structure may change size, and should not be included in client
  27.    data structures.  Only use pointers to NXStreams.
  28.  */
  29. typedef struct _NXStream {
  30.     unsigned int    magic_number;    /* to check stream validity */
  31.     unsigned char  *buf_base;    /* data buffer */
  32.     unsigned char  *buf_ptr;    /* current buffer pointer */
  33.     int        buf_size;    /* size of buffer */
  34.     int        buf_left;    /* # left till buffer operation */
  35.     long        offset;     /* position of beginning of buffer */
  36.     int        flags;        /* info about stream */
  37.     int        eof;
  38.     const struct stream_functions
  39.             *functions;    /* functions to implement stream */
  40.     void        *info;        /* stream specific info */
  41. } NXStream;
  42.  
  43.  
  44. struct stream_functions {
  45.     /*
  46.      * Called to read count bytes into buf.  If you arent doing any
  47.      * special buffer management, you can set this proc to be
  48.      * NXDefaultRead.  It should return how many bytes were read.
  49.      */
  50.     int    (*read_bytes)(NXStream *s, void *buf, int count);
  51.  
  52.     /*
  53.      * Called to write count bytes from buf.  If you arent doing any
  54.      * special buffer management, you can set this proc to be
  55.      * NXDefaultWrite.  It should return how many bytes were written.
  56.      */
  57.     int    (*write_bytes)(NXStream *s, const void *buf, int count);
  58.  
  59.     /*
  60.      * Called by the write routine to deal with a full output buffer.
  61.      * This routine should make space for more characters to be
  62.      * written.  NXDefaultWrite assumes this routine empties the
  63.      * buffer.  It should return how many bytes were written.
  64.      * If it returns -1, then a NX_illegalWrite exception will be raised.
  65.      */
  66.     int    (*flush_buffer)(NXStream *s);
  67.  
  68.     /*
  69.      * Called by the read routine to deal with an empty input buffer.
  70.      * This routine should provide more characters to be read.
  71.      * NXDefaultRead assumes this routine adds new characters
  72.      * to the buffer.  It should return how many bytes were read.
  73.      * If it returns -1, then a NX_illegalRead exception will be raised.
  74.      */
  75.     int    (*fill_buffer)(NXStream *s);
  76.  
  77.     /*
  78.      * Called to flip the mode of the stream between reading and writing.
  79.      * The current state can be found by masking the flags field with
  80.      * NX_READFLAG and NX_WRITEFLAG.  The caller will update the flags.
  81.      */
  82.     void    (*change_buffer)(NXStream *s);
  83.  
  84.     /*
  85.      * Called to seek the stream to a certain position.  It must update
  86.      * any affected elements in the NXStream struct.
  87.      */
  88.     void    (*seek)(NXStream *s, long offset);
  89.  
  90.     /*
  91.      * Called to free any resources used by the stream.  This proc
  92.      * should free the buffer if not allocated by NXStreamCreate.
  93.      */
  94.     void    (*destroy)(NXStream *s);
  95. };
  96.  
  97. /*
  98.  *    Modes
  99.  */
  100.  
  101. #define NX_READONLY        1    /* read on stream only */
  102. #define NX_WRITEONLY        2    /* write on stream only */
  103. #define NX_READWRITE        4    /* do read & write */
  104.  
  105. /*
  106.  *    Seeking Modes - determines meaning of offset passed to NXSeek
  107.  */
  108.  
  109. #define NX_FROMSTART        0    /* relative to start of file */
  110. #define NX_FROMCURRENT        1    /* relative to current position */
  111. #define NX_FROMEND        2    /* relative to end of file */
  112.  
  113. /*
  114.  *    Private Flags and Private Routines
  115.  */
  116.  
  117. #define NX_READFLAG    1        /* stream is for reading */
  118. #define NX_WRITEFLAG    (1 << 1)    /* stream is for writing */
  119. #define    NX_USER_OWNS_BUF    (1 << 2)    /* used by memory streams */
  120. #define NX_EOS            (1 << 3)    /* end of stream detected */
  121. #define NX_NOBUF        (1 << 4)    /* whether lib alloc'ed buf */
  122. #define NX_CANWRITE        (1 << 5)
  123. #define NX_CANREAD        (1 << 6)
  124. #define NX_CANSEEK        (1 << 7)
  125.  
  126. /* private functions for NXGetc and NXPutc */
  127. NEXTPDO int _NXStreamFillBuffer(NXStream *s);
  128. NEXTPDO int _NXStreamFlushBuffer(NXStream *s, unsigned char c);
  129. NEXTPDO int _NXStreamChangeBuffer(NXStream *s, unsigned char ch);
  130.  
  131.  
  132. /*
  133.  *        Macro operations.
  134.  */
  135.  
  136. #define NXPutc(s, c) \
  137.     ( ((s)->flags & NX_WRITEFLAG) ? \
  138.     ( --((s)->buf_left) >= 0 ? (*(s)->buf_ptr++ = (unsigned char)(c)) : \
  139.     (_NXStreamFlushBuffer((s), (unsigned char)(c)), (unsigned char)0) ) : \
  140.     _NXStreamChangeBuffer((s), (unsigned char)(c)) ) \
  141.  
  142. #define NXGetc(s)                        \
  143.     ( ((s)->flags & NX_READFLAG) ?                \
  144.     ( --((s)->buf_left) >= 0 ? ((int)(*(s)->buf_ptr++)) :    \
  145.         _NXStreamFillBuffer((s)) ) :            \
  146.     _NXStreamChangeBuffer((s), (unsigned char)(0)) )
  147.  
  148. #define NXAtEOS(s) (s->flags & NX_EOS)
  149.  
  150.  
  151. /*
  152.  *        Procedure declarations (exported).
  153.  */
  154.  
  155. NEXTPDO int NXFlush(NXStream *s);        
  156.  /*
  157.     flush the current contents of stream s.  Returns the number of chars
  158.     written.
  159.   */
  160.   
  161. NEXTPDO void NXSeek(NXStream *s, long offset, int mode);        
  162.  /*
  163.     sets the current position of the stream.  Mode is either NX_FROMSTART,
  164.     NX_FROMCURRENT, or NX_FROMEND.
  165.   */
  166.   
  167. NEXTPDO long NXTell(NXStream *s);        
  168.  /*
  169.     reports the current position of the stream.
  170.   */
  171.   
  172. #define NXRead(s, buf, count)    \
  173.         ((*s->functions->read_bytes)((s), (buf), (count)))
  174.  /*
  175.     int NXRead(NXStream *s, void *buf, int count) 
  176.     
  177.     read count bytes starting at pointer buf from stream s.  Returns the
  178.     number of bytes read.
  179.   */
  180.   
  181. #define NXWrite(s, buf, count)        \
  182.         ((*s->functions->write_bytes)((s), (buf), (count)))
  183.  /*
  184.     int NXWrite(NXStream *s, const void *buf, int count) 
  185.     
  186.     write count bytes starting at pointer buf to stream s.  Returns the
  187.     number of bytes written.
  188.   */
  189.   
  190. NEXTPDO void NXPrintf(NXStream *s, const char *format, ...);
  191. NEXTPDO void NXVPrintf(NXStream *s, const char *format, va_list argList);
  192.  /*
  193.     writes args according to format string to stream s.  The first routine
  194.     takes its variable arguments on the stack, the second takes a va_list
  195.     as defined in <stdarg.h>.
  196.   */
  197.   
  198. NEXTPDO int NXScanf(NXStream *s, const char *format, ...);
  199. NEXTPDO int NXVScanf(NXStream *s, const char *format, va_list argList);
  200.  /*
  201.     reads args from stream s according to format string.  The first routine
  202.     takes its variable arguments on the stack, the second takes a va_list
  203.     as defined in <varargs.h>.
  204.   */
  205.  
  206. NEXTPDO void NXUngetc(NXStream *s);        
  207.  /*
  208.     backs up one character previously read by getc.  Only a single character
  209.     can be backed over between reads.
  210.   */
  211.   
  212. NEXTPDO void NXClose(NXStream *s);        
  213.  /*
  214.     closes stream s.
  215.   */
  216.   
  217. NEXTPDO NXStream *NXOpenFile(int fd, int mode);
  218.  /*
  219.     opens a file stream on file descriptor fd with access mode. mode
  220.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE.
  221.     The fd should have the same access rights as the mode passed in.
  222.     When NXClose is called on a file stream, the fd is not closed.
  223.   */
  224.  
  225. NEXTPDO NXStream *NXOpenPort(port_t port, int mode);
  226.  /*
  227.     opens a stream on a MACH port with access mode. If mode is NX_READONLY,
  228.     messages will be received on port.  If mode is NX_WRITEONLY,
  229.     messages will be sent to port.  mode can not be NX_READWRITE.
  230.     These streams are not positionable, thus you cannot call NXSeek
  231.     with a port stream.  
  232.   */
  233.     
  234. NEXTPDO NXStream *NXOpenMemory(const char *addr, int size, int mode);
  235.  /*
  236.     Opens a stream on memory with access mode. mode
  237.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE
  238.     When NXClose is called on a memory stream, the internal buffer is
  239.     not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  240.     use vm_deallocate to free it.
  241.   */
  242.  
  243. NEXTPDO NXStream *NXMapFile(const char *name, int mode);
  244.  /*
  245.     opens a stream on memory with access mode, initializing the
  246.     memory with the contents of a file. mode
  247.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE
  248.     When NXClose is called on a memory stream, the internal buffer is
  249.     not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  250.     use vm_deallocate to free it. Use NXSaveToFile to write the 
  251.     contents of the memory stream to a file.
  252.   */
  253.  
  254. #if !defined(WIN32)
  255. extern NXStream *NXGetStreamOnSection(const char *fileName, const char *segmentName, const char *sectionName);
  256.  /*
  257.     opens a read-only memory stream with the contents of the named section
  258.     within the file.  When NXClose is called on a memory stream, the internal
  259.     buffer is not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  260.     use vm_deallocate to free it.
  261.   */
  262. #endif
  263.  
  264. NEXTPDO int NXSaveToFile(NXStream *s, const char *name);
  265.  /*
  266.     Write the contents of a memory stream to a file .
  267.   */
  268.  
  269. NEXTPDO void NXGetMemoryBuffer(NXStream *s, char **addr, int *len, int *maxlen);
  270.  /*
  271.     return the memory buffer, the current length, and the max length
  272.     of the buffer. Use the maxlen value when you vm_deallocate.
  273.   */
  274.  
  275. NEXTPDO void NXCloseMemory(NXStream *s, int option);
  276.  /*
  277.     Closes a memory stream, with options NX_FREEBUFFER which frees the
  278.     internal buffer, NX_TRUNCATEBUFFER which truncates to buffer to
  279.     the size of the data, and NX_SAVEBUFFER which does nothing to the
  280.     buffer. The stream is then closed and freed.
  281.   */
  282.  
  283. #define NX_FREEBUFFER        0    /* constants for NXCloseMemory */
  284. #define NX_TRUNCATEBUFFER    1
  285. #define NX_SAVEBUFFER        2
  286.  
  287.  
  288. typedef void NXPrintfProc(NXStream *stream, void *item, void *procData);
  289.  /*
  290.     A proc that is registered to format and output item on the given stream.
  291.   */
  292.  
  293. NEXTPDO void NXRegisterPrintfProc(char formatChar, NXPrintfProc *proc,
  294.                             void *procData);
  295.  /*
  296.     Registers a NXPrintProc for a format character used in the format
  297.     string for NXPrintf or NXVPrintf.  If formatChar is used in a
  298.     format string, proc will be called with the corresponding argument
  299.     passed to NXPrintf.  The format characters in the string "vVwWyYzZ"
  300.     are available for non-NeXT applications to use; the rest are reserved
  301.     for future use by NeXT.  procData is for client data that will be
  302.     blindly passed along to the proc.
  303.   */
  304.  
  305. #define NX_STREAMERRBASE 2000    /* 1000 error codes for us start here */
  306.  
  307. /* Errors that stream routines raise.  When these exceptions are raised,
  308.    the first data element is always the NXStream * being operated on,
  309.    or zero if thats not applicable.  The second is any error code
  310.    returned from the operating system.
  311.  */
  312. typedef enum _NXStreamErrors {
  313.     NX_illegalWrite = NX_STREAMERRBASE,
  314.     NX_illegalRead,
  315.     NX_illegalSeek,
  316.     NX_illegalStream,
  317.     NX_streamVMError
  318. } NXStreamErrors;
  319.  
  320. #endif
  321.